home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / INDENT3.ARJ / INDENT.MAN < prev    next >
Text File  |  1992-08-02  |  14KB  |  361 lines
  1.  
  2.  
  3.  
  4. INDENT(1)           UNIX Programmer's Manual            INDENT(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      indent - indent and format C program source
  10.  
  11. SYNOPSIS
  12.      indent  [ input-file [ output-file ] ] [ -bad | -nbad ]
  13.             [ -bap | -nbap ] [ -bbb | -nbbb ] [ -bc | -nbc ]
  14.             [ -bl | -br ] [ -cn ] [ -cdn ] [ -cdb | -ncdb ]
  15.             [ -ce | -nce ] [ -cin ] [ -clin ] [ -dn ] [ -din ]
  16.             [ -dj | -ndj ] [ -ei | -nei ] [ -fc1 | -nfc1 ]
  17.             [ -in ] [ -ip | -nip ] [ -ln ] [ -lcn ]
  18.             [ -lp | -nlp ] [ -npro ] [ -pcs | -npcs ]
  19.             [ -ps | -nps ] [ -psl | -npsl ] [ -sc | -nsc ]
  20.             [ -sob | -nsob ] [ -st ] [ -troff ] [ -v | -nv ]
  21.  
  22. DESCRIPTION
  23.      Indent is a C program formatter.  It reformats the C program
  24.      in the input-file according to the switches.  The switches
  25.      which can be specified are described below. They may appear
  26.      before or after the file names.
  27.  
  28.      NOTE: If you only specify an input-file, the formatting is
  29.      done `in-place', that is, the formatted file is written back
  30.      into input-file and a backup copy of input-file is written
  31.      in the current directory.  If input-file is named
  32.      `/blah/blah/file.foo', the backup file is named file.bak.
  33.  
  34.      If output-file is specified, indent checks to make sure it
  35.      is different from input-file.
  36.  
  37. OPTIONS
  38.      The options listed below control the formatting style
  39.      imposed by indent.
  40.  
  41.      -bad,-nbad     If -bad is specified, a blank line is forced
  42.                     after every block of declarations.  Default:
  43.                     -nbad.
  44.  
  45.      -bap,-nbap     If -bap is specified, a blank line is forced
  46.                     after every procedure body.  Default: -nbap.
  47.  
  48.      -bbb,-nbbb     If -bbb is specified, a blank line is forced
  49.                     before every block comment.  Default: -nbbb.
  50.  
  51.      -bc,-nbc       If -bc is specified, then a newline is forced
  52.                     after each comma in a declaration. -nbc turns
  53.                     off this option.  The default is -nbc.
  54.  
  55.      -br,-bl        Specifying -bl lines up compound statements
  56.                     like this:
  57.                         if (...)
  58.                         {
  59.                             code
  60.  
  61.  
  62.  
  63. Printed 2/20/86        September 10, 1985                       1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. INDENT(1)           UNIX Programmer's Manual            INDENT(1)
  71.  
  72.  
  73.  
  74.                         }
  75.                     Specifying -br (the default) makes them look
  76.                     like this:
  77.                         if (...) {
  78.                             code
  79.                         }
  80.  
  81.      -cn            The column in which comments on code start.
  82.                     The default is 33.
  83.  
  84.      -cdn           The column in which comments on declarations
  85.                     start.  The default is for these comments to
  86.                     start in the same column as those on code.
  87.  
  88.      -cdb,-ncdb     Enables (disables) the placement of comment
  89.                     delimiters on blank lines.  With this option
  90.                     enabled, comments look like this:
  91.                          /*
  92.                           * this is a comment
  93.                           */
  94.                     Rather than like this:
  95.                          /* this is a comment */
  96.                     This only affects block comments, not com-
  97.                     ments to the right of code. The default is
  98.                     -cdb.
  99.  
  100.      -ce,-nce       Enables (disables) forcing `else's to cuddle
  101.                     up to the immediately preceding `}'.  The
  102.                     default is -ce.
  103.  
  104.      -cin           Sets the continuation indent to be n.  Con-
  105.                     tinuation lines will be indented that far
  106.                     from the beginning of the first line of the
  107.                     statement.  Parenthesized expressions have
  108.                     extra indentation added to indicate the nest-
  109.                     ing, unless -lp is in effect.  -ci defaults
  110.                     to the same value as -i.
  111.  
  112.      -clin          Causes case labels to be indented n tab stops
  113.                     to the right of the containing switch state-
  114.                     ment.  -cli0.5 causes case labels to be
  115.                     indented half a tab stop.  The default is
  116.                     -cli0.  (This is the only option that takes a
  117.                     fractional argument.)
  118.  
  119.      -dn            Controls the placement of comments which are
  120.                     not to the right of code.  Specifying -d1
  121.                     means that such comments are placed one
  122.                     indentation level to the left of code.  The
  123.                     default -d0 lines up these comments with the
  124.                     code.  See the section on comment indentation
  125.                     below.
  126.  
  127.  
  128.  
  129. Printed 2/20/86        September 10, 1985                       2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. INDENT(1)           UNIX Programmer's Manual            INDENT(1)
  137.  
  138.  
  139.  
  140.      -din           Specifies the indentation, in character posi-
  141.                     tions, from a declaration keyword to the fol-
  142.                     lowing identifier.  The default is -di16.
  143.  
  144.      -dj,-ndj       -dj left justifies declarations.  -ndj
  145.                     indents declarations the same as code.  The
  146.                     default is -ndj.
  147.  
  148.      -ei,-nei       Enables (disables) special else-if process-
  149.                     ing.  If enabled, ifs following elses will
  150.                     have the same indentation as the preceding if
  151.                     statement.  The default is -ei.
  152.  
  153.      -fc1,-nfc1     Enables (disables) the formatting of comments
  154.                     that start in column 1.  Often, comments
  155.                     whose leading `/' is in column 1 have been
  156.                     carefully hand formatted by the programmer.
  157.                     In such cases, -nfc1 should be used.  The
  158.                     default is -fc1.
  159.  
  160.      -in            The number of spaces for one indentation
  161.                     level.  The default is 8.
  162.  
  163.      -ip,-nip       Enables (disables) the indentation of parame-
  164.                     ter declarations from the left margin.  The
  165.                     default is -ip.
  166.  
  167.      -ln            Maximum length of an output line.  The
  168.                     default is 78.
  169.  
  170.      -lp,-nlp       Lines up code surrounded by parenthesis in
  171.                     continuation lines.  If a line has a left
  172.                     paren which is not closed on that line, then
  173.                     continuation lines will be lined up to start
  174.                     at the character position just after the left
  175.                     paren.  For example, here is how a piece of
  176.                     continued code looks with -nlp in effect:
  177.                         p1 = firstprocedure(secondprocedure(p2, p3),
  178.                             thirdprocedure(p4, p5));
  179.                     With -lp in effect (the default) the code
  180.                     looks somewhat clearer:
  181.                         p1 = firstprocedure(secondprocedure(p2, p3),
  182.                                              thirdprocedure(p4, p5));
  183.                     Inserting two more newlines we get:
  184.                         p1 = firstprocedure(secondprocedure(p2,
  185.                                                               p3),
  186.                                              thirdprocedure(p4,
  187.                                                              p5));
  188.  
  189.      -npro          Causes the profile file, `PATH/indent.pro'
  190.                     to be ignored.
  191.  
  192.  
  193.  
  194.  
  195. Printed 2/20/86        September 10, 1985                       3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. INDENT(1)           UNIX Programmer's Manual            INDENT(1)
  203.  
  204.  
  205.  
  206.      -pcs,-npcs     If true (-pcs) all procedure calls will have
  207.                     a space inserted between the name and the
  208.                     `('.  The default is -npcs.
  209.  
  210.      -ps,-nps       If true (-ps) the pointer following operator
  211.                     `->' will be surrounded by spaces on either
  212.                     side.  The default is -nps.
  213.  
  214.      -psl,-npsl     If true (-psl) the names of procedures being
  215.                     defined are placed in column 1 - their types,
  216.                     if any, will be left on the previous lines.
  217.                     The default is -psl.
  218.  
  219.      -sc,-nsc       Enables (disables) the placement of asterisks
  220.                     (`*'s) at the left edge of all comments.  The
  221.                     default is -sc.
  222.  
  223.      -sob,-nsob     If -sob is specified, indent will swallow
  224.                     optional blank lines.  You can use this to
  225.                     get rid of blank lines after declarations.
  226.                     Default: -nsob.
  227.  
  228.      -st            Causes indent to take its input from stdin,
  229.                     and put its output to stdout.
  230.  
  231.      -Ttypename     Adds typename to the list of type keywords.
  232.                     Names accumulate: -T can be specified more
  233.                     than once.  You need to specify all the
  234.                     typenames that appear in your program that
  235.                     are defined by typedefs - nothing will be
  236.                     harmed if you miss a few, but the program
  237.                     won't be formatted as nicely as it should.
  238.                     This sounds like a painful thing to have to
  239.                     do, but it's really a symptom of a problem in
  240.                     C: typedef causes a syntactic change in the
  241.                     language and indent can't find all typedefs.
  242.  
  243.      -troff         Causes indent to format the program for pro-
  244.                     cessing by troff.  It will produce a fancy
  245.                     listing in much the same spirit as vgrind.
  246.                     If the output file is not specified, the
  247.                     default is standard output, rather than for-
  248.                     matting in place.
  249.  
  250.      -v,-nv         -v turns on `verbose' mode; -nv turns it off.
  251.                     When in verbose mode, indent reports when it
  252.                     splits one line of input into two or more
  253.                     lines of output, and gives some size statis-
  254.                     tics at completion. The default is -nv.
  255.  
  256. FURTHER DESCRIPTION
  257.  
  258.  
  259.  
  260.  
  261. Printed 2/20/86        September 10, 1985                       4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. INDENT(1)           UNIX Programmer's Manual            INDENT(1)
  269.  
  270.  
  271.  
  272.      You may set up your own `profile' of defaults to indent by
  273.      creating a file called indent.pro anywhere on your path
  274.      including what-ever switches you like. If indent is run and
  275.      a profile file exists, then it is read to set up the
  276.      program's defaults.  The switches should be separated by
  277.      spaces, tabs or newlines.  Switches on the command line,
  278.      however, override profile switches.
  279.  
  280.      Comments
  281.  
  282.      `Box' comments.  Indent assumes that any comment with a dash
  283.      or star immediately after the start of comment (that is,
  284.      `/*-' or `/**') is a comment surrounded by a box of stars.
  285.      Each line of such a comment is left unchanged, except that
  286.      its indentation may be adjusted to account for the change in
  287.      indentation of the first line of the comment.
  288.  
  289.      Straight text.  All other comments are treated as straight
  290.      text.  Indent fits as many words (separated by blanks, tabs,
  291.      or newlines) on a line as possible.  Blank lines break para-
  292.      graphs.
  293.  
  294.      Comment indentation
  295.  
  296.      If a comment is on a line with code it is started in the
  297.      `comment column', which is set by the -cn command line
  298.      parameter.  Otherwise, the comment is started at n indenta-
  299.      tion levels less than where code is currently being placed,
  300.      where n is specified by the -dn command line parameter.  If
  301.      the code on a line extends past the comment column, the com-
  302.      ment starts further to the right, and the right margin may
  303.      be automatically extended in extreme cases.
  304.  
  305.      Preprocessor lines
  306.  
  307.      In general, indent leaves preprocessor lines alone.  The
  308.      only reformatting that it will do is to straighten up trail-
  309.      ing comments.  It leaves embedded comments alone.  Condi-
  310.      tional compilation (#ifdef...#endif) is recognized and
  311.      indent attempts to correctly compensate for the syntactic
  312.      peculiarities introduced.
  313.  
  314.      C syntax
  315.  
  316.      Indent understands a substantial amount about the syntax of
  317.      C, but it has a `forgiving' parser.  It attempts to cope
  318.      with the usual sorts of incomplete and misformed syntax.  In
  319.      particular, the use of macros like:
  320.              #define forever for(;;)
  321.  
  322.  
  323.  
  324. Printed 2/20/86        September 10, 1985                       5
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331. INDENT(1)           UNIX Programmer's Manual            INDENT(1)
  332.  
  333.  
  334.  
  335.      is handled properly.
  336.  
  337. FILES
  338.      PATH.\indent.pro  profile file
  339.  
  340. BUGS
  341.      Indent has even more switches than ls.
  342.  
  343.      A common mistake that often causes grief is typing:
  344.          indent *.c
  345.      to the shell in an attempt to indent all the C programs in a
  346.      directory.  This is probably a bug, not a feature.
  347.  
  348. CHANGES
  349.      added a couple of new switches:
  350.     -nfca   disables comment re-formatting
  351.         -fca    enables comment re-formatting (default)
  352.     -kr     borrowed code: impliments K&R's formatting style
  353.     -gnu        "        : implements GNU's formatting style
  354.         -tn     changes the size of a tab. (default=8)
  355.      found a bunch of bugs that are corrected:
  356.     a preprocessor statement w/ a comment would bomb.
  357.     it inverted sequences w/ an equel sign: ``a=*temp '' would
  358.     become ``a*=temp''
  359.      changed alot of the code. i don't know where but I did. ran the
  360.      all of the code: ``indent -kr .c.''
  361.